• TOP

    • Gloss

    To view this file with Gloss-style markdown applied, you can double-click on the HTML version "Gloss.html" in IntraMine's Documentation folder, or click on the '?' in the navigation bar and then click on "Gloss.txt" listed there. For the plain text source, open Documentation/Gloss.txt in a text editor.
    NOTE: "tricks" such as zero width spaces, fat asterisks ✱, and images are used to avoid Gloss processing below, so you can see the original text followed by how Gloss renders it.

    Overview

    Gloss is a markdown variant that concentrates on: minimal, memorable markdown that looks good in the source text; automatic linking to files on your local and intranet storage (these are called FLASH links below); and glossary popups.
    IntraMine applies Gloss automatically to .txt files. At present, there is no special extension for Gloss files.
    Regular markdown doesn't do links to files on local storage, and editors typically limit automatic linking to the files in your project. With FLASH links, if you want a link to qtcpserver.cpp, and that name is unique across all your local storage, then that's all you have to type to get a link to p:\qt\5.12.5\src\qtbase\src\network\socket\qtcpserver.cpp: the plain file name without any directories or drive or quotes or brackets, or any other adornments. If there are two or more files with the same name, IntraMine picks the one that's closest to where you're typing, based on directory hops up and down to go from one to the other. Paths are selected from among those that you've indicated are "of interest" to you, based on your list of directory paths in data/search_directories.txt. In the rare case where the file name alone is ambiguous, you can add one or more directory names in any order in any sequence to pin down the file you want. You can leave out directory names that don't constrain the instance wanted. And if you need a drive letter to do the job, put it first.
    A glossary is a necessity for a project of any size. You've probably seen already how they work in IntraMine: any defined term, such as FLASH links, has a dotted underline in the text, and if you pause your cursor over the term a definition pops up. These are called glossary popups in IntraMine, and in a slightly recursive manner your definitions can also be marked up with Gloss, including FLASH links and styling. For details see "Glossary popups.txt".
    IntraMine's Viewer fully implements Gloss, and almost all of Gloss's features are also available in standalone files produced by gloss2html.pl (for standalone Gloss, see "gloss2html.pl for standalone Gloss files.txt").
    IntraMine's Editor shows FLASH links and glossary popups for .txt files.
    And most of Gloss is available in ToDo items - see "ToDo.txt#Gloss markdown can be used in ToDo items". The main difference is that links to files must use a full path and be contained in double quotes (eg "C:\folder1\folder2\afile.txt").
    Gloss is for developers (like you) who need to crank out good looking spec, design, test, how-to, development logs, meeting notes, and sundry other documents designed for in-house or personal use. And do so with the absolute minimum of additional markup characters, in a way that's easy to remember. You know, so you'll actually use it.
    Gloss processing is fully applied to all .txt files by the Viewer. A subset of Gloss including automatic linking, glossary popups, a synchronized table of contents, and image hovers is also applied to source files. IntraMine's Editor is well suited for editing the source of Glossed files, and shows "live" automatic links and glossary popups. And gloss2html.pl generates the promised fully standalone HTML versions from Gloss sources, either single files or a whole folder at once, with images inlined or as hovers.
    Gloss also does

     • an auto generated and synchronized table of contents (currently a table of contents is supported for .txt, Perl, Pod, C / C++, Go, JavaScript, CSS, Clojure, Erlang, OCaml, PHP, Python, Ruby, TypeScript, Rust, Java, C#, VBScript(.vb), VB.NET(.vbs), Haskell, Julia, Fortran, COBOL.)

     • "Headings": h1 h2 h3, done with underlining using at least five =====, -----, ~~~~~. And also h1 h2 etc using "# ", "## " etc at the start of a line.

     • "Tables": write "TABLE" at the start of a line, put headers on the next line, data on following lines, and separate cells with one or more tabs: the table ends when a line has no tabs. More below, but that's basically it.

     • "Lists" both numbered and bulleted.

     • "Emphasis": bold, italic, and my $codeFragment = 42;.

     • highlighting of any word or short phrase you select, in the text and down the scroll bar. (Due to technical limitations aka my brain size, only single words can be highlighted in CODE/ENDCODE blocks.)

     • "image hovers": any mention of an image becomes a link to the image, and stopping your cursor over the link will pop up an instant view of the image. If you haven't been using images in your source files, it's because you didn't have image hovers. For text files there's an "Inline Images" button at the top of the Viewer that lets you switch between the default image hovers and fully displayed images.

     • "Code blocks": if you put some code between CODE and ENDCODE lines it will be styled up a bit.

    How to

    Glossary popups

    If you pause your cursor over a defined term such as Gloss, a rich definition will pop up. IntraMine supports two glossaries, one for general use when displaying source and text files, and one for use when converting text files to HTML with the Glosser service or the gloss2html.pl Perl program. Glosser was used to generate the HTML version of this document.
    For general use: create a glossary_master.txt file anywhere within a folder that's listed for indexing in your data/search_directories.txt file. There's a sample glossary_master.txt file included at the top of your IntraMine folder: open that and follow the instructions at the top to get going. The basic format of a glossary entry is term colon definition, and the definition continues until the next paragraph with a colon.
    For generating standalone HTML with gloss2html.pl: use "glossary.txt" as the name of your glossary file, and put it at the top of the folder containing text documents that you want to convert to HTML. The format is the same as for glossary_master.txt files. An example glossary.txt file is included at the top of IntraMine's Documentation folder, and it also has instructions at the top.
    "Glossary popups.txt" has slightly more details, with a focus on creating glossary_master.txt files for general use.

    Table of Contents

    Gloss generates a Table of Contents (TOC) automatically for:

     • headings in text files (see just below)

     • function, method, class, and struct definitions in source files.

    Currently a table of contents is supported for .txt, Perl, Pod, C / C++, Go, JavaScript, CSS, Clojure, Erlang, OCaml, PHP, Python, Ruby, TypeScript, Rust, Java, C#, VBScript(.vb), VB.NET(.vbs), Haskell, Julia, Fortran, COBOL. Alas, non-ASCII definition names are not currently supported in C or C++ or Java and I don't know how to correct that.
    The Table of Contents is done alphabetically in source files, and in order of occurrence in text files.
    The selected item in the TOC updates automatically to synchronize with the position you're viewing in a document as you scroll.
    A little green double-headed arrow doohickey up top lets you collapse/expand the TOC width.

    Headings

    To mark a line as a heading, underline it with five or more of the same character: equals (=) for top level, hyphen (-) for next level, and tilde (~) for the lowest level.
           Heading underline characters
    Underline withTo get
    =====h1
    -----h2
    ~~~~~h3
    Examples:
    Top level heading
    ​=================
    produces
    Next level heading
    ​------------------
    produces
    Lowest level heading
    ​~~~~~~~~~~~~~~~~~~~~
    produces

    Hashed headings

    For the sake of compatibility you can also create a heading by putting one or more hashes (#) at the beginning of a line, then one or more spaces or tabs, and then the actual heading text. ### heading produces an h3 heading etc. These work fine for the HTML result, but the effect in the source is reversed from expectations, with more hashes meaning a less important heading.
    Note a blank line must precede the # heading line, unless of course it's the first line. This suppresses problems with quoting code from a language where a '#' introduces a comment. If you don't want that: open data/intramine_config_6.txt, and change the value of HASH_HEADING_NEEDS_BLANK_BEFORE to 0. Then restart IntraMine.

    Horizontal rules

    Put three or four equals signs '=' or hyphens'-'or tildes '~' at the beginning of a line, and nothing else on the line, to produce a horizontal rule. A rule done with "===" will be slightly more noticeable than one done with "---" or "~~~".
    Since IntraMine uses a monospaced font for text display, horizontal rules can help code examples stand out.
    Example:
    ​---
    #special-index-wrapper th {
    text-align: center;
    }
    ​---
    produces
    #special-index-wrapper th {
    text-align: center;
    }
    When a source or text file is viewed with IntraMine, local or NAS file mentions within it will be turned into links, provided the file mentioned is in an indexed location. If it isn't, you'll need a full path to get a link. So needless to say indexing all the files you'll be interested in is strongly recommended. In the details below I'll assume a file is in an indexed directory unless a full path is used. For details on how to index folders, see "Configuring folders to index and monitor.txt".
    For the details on linking with IntraMine please see "FLASH links.txt".

    Tables

    Simple tables

    Here's a simple Gloss table:
    ​TABLE CodeMirror linkType and class
    linkType Class
    file cmAutoLink
    image cmAutoLinkImg
    web cmAutoLinkNoEdit
    (internal) cmInternalLink
    which displays as
           CodeMirror linkType and class
    linkTypeClass
    filecmAutoLink
    imagecmAutoLinkImg
    webcmAutoLinkNoEdit
    (internal)cmInternalLink
    To make a simple table:

     • put "TABLE" at the beginning of a line, optionally followed by a space and a caption

     • on the next line, put column headers separated by one or more tabs

     • on the following lines put the data, again with columns separated by one or more tabs

     • the table ends when there's a line with no tabs.

    If you want a blank cell, put a space. No toothpicks |, no pavement _, you don't even have to use enough tabs to make it all line up in the original text (but I know that you will).

    Cell span and alignment

    You can have fancier tables if you want, but of course at the price of having to know and type a bit more.
    Put <N> at the beginning of cell contents to indicate how many columns the text should span, where N is an integer. This isn't needed for the rightmost cell, it will take however many columns are remaining to the right.
    Put <L>, <R>, or <C> at the beginning of a cell to indicate left, right, or center alignment. Cell text is aligned left by default, except for text spanning multiple cells, which is center-aligned by default.
    To combine span and alignment, put the alignment and then span in the '<>' at the beginning of the cell's contents, eg <R3> for text aligned right in a three-column span.
    ​TABLE Column span demo
    One Hdr Two Hdr Three Hdr Four Hdr Five Hdr
    d11 <3>d12 3 cells d15
    d21 d22 d23 d24 d25
    d31 d32 <L>d33 3 cells left
    d41 d42 d43 d44 d45
    <R3>d51 3 cells right d54 d55
    Column span demo
    One HdrTwo HdrThree HdrFour HdrFive Hdr
    d11d12 3 cellsd15
    d21d22d23d24d25
    d31d32d33 3 cells left
    d41d42d43d44d45
    d51 3 cells rightd54d55
    ​TABLE Cell alignment
    Temperature Range in Kelvin
    Class Description <R>Low <R>High
    <C>O blue <R>30,000 <R>♾️?
    <C>B blue white <R>10,000 <R>30,000
    <C>A white <R>7,500 <R>10,000
    <C>F yellow white <R>6,000 <R>7,500
    <C>G yellow <R>5,200 <R>6,000
    <C>K light orange <R>3,700 <R>5,200
    <C>M orange red <R>2,400 <R>3,700
    Cell alignment
    Temperature Range in Kelvin
    ClassDescriptionLowHigh
    Oblue30,000♾️?
    Bblue white10,00030,000
    Awhite7,50010,000
    Fyellow white6,0007,500
    Gyellow5,2006,000
    Klight orange3,7005,200
    Morange red2,4003,700

    Gloss vs Markdown tables

    Here's a simple Markdown style table, in plain old HTML:
    <table>
    <th>
    <td>First header</td><td>Second</td><td>Third</td>
    </th>
    <tr>
    <td>Entry one</td><td>Another entry</td><td>Last entry on first row</td>
    </tr>
    <tr>
    <td>Second data row first cell</td><td>row 2 cell 2</td><td>Last entry in table</td>
    </tr>
    </table>
    And here's the equivalent Gloss table:
    ​​TABLE
    First header Second Third
    Entry one Another entry Last entry on first row
    Second data row first cell row 2 cell 2 Last entry in table
    which produces
    First headerSecondThird
    Entry oneAnother entryLast entry on first row
    Second data row first cellrow 2 cell 2Last entry in table
    The HTML version needs 268 characters, and many of them are special. The Gloss table needs 151 characters, of which only five ("TABLE") are at all special.

    Gloss vs MultiMarkdown tables

    Here's a MultiMarkdown table, from
    http://fletcher.github.io/MultiMarkdown-5/tables.html
    | | Grouping ||
    First Header | Second Header | Third Header |

    ◦ | :-----------: | -----------: |

    Content | ✱Long Cell✱ ||
    Content | ✱✱Cell✱✱ | Cell |
    New section | More | Data |
    And more | With an escaped '\|' ||
    [Prototype table]
    ()
    Here's the same table in Gloss, as closely as possible:
    ​TABLE Prototype table
    Grouping
    First Header <C>Second Header <R>Third Header
    Content ✱Long Cell✱
    Content <C>✱✱Cell✱✱ <R>Cell
    New section <C>More <R>Data
    And more With an escaped '|'
    Prototype table
    Grouping
    First HeaderSecond HeaderThird Header
    ContentLong Cell
    ContentCellCell
    New sectionMoreData
    And moreWith an escaped '|'
    MultiMarkdown needs 310 characters, versus 206 for Gloss.
    (Note the divider line just above "New section" is produced by a line in the source containing a single tab, which Gloss collapses vertically into a line.)

    Wider columns

    IntraMine's tables rely on the browser to sort out column widths, but sometimes a column can end up being too narrow, especially if the browser window isn't very wide. To force a column to be wider, add spaces or non-breaking spaces at the end of the heading for the column. Regular spaces seem to do the trick too sometimes, but not always.
    To type a non-breaking space on a Windows box, hold down the ALT key and type 0160. The numbers 0160 must be typed on the numeric keypad for this to work. And NumLock must also be on. My record for remembering that is, I think, about five years.

    Lists

    You can have unordered (bulleted) or ordered (numbered) lists.

    Unordered lists

     • two levels are supported

     • an unordered list item begins flush left with a '-', '+', or '*'.

     • optionally you can put one or more spaces at the beginning of the line.

    ◦ if you put two or more of '-', '+', or '*', eg '--' or '+++', you'll get a second-level entry. To make it prettier in the original text, you can insert spaces at the beginning of the line.

    A top-level or second-level item can continue in following paragraphs. To have the following paragraphs count as part of an item, begin each with one or more tabs or spaces. The leading spaces or tabs will be suppressed in the HTML display.

    This paragraph begins with three spaces in the source, as does the one before.

    ◦ Another second-level item, with excessive spaces.

    To clarify some overlap with horizontal rules: the three or four hyphens '-' for a horizontal rule must be flush left on a line, and followed by nothing else. If there are spaces before the three or four '-' or text afterwards then they count as the start of a second order list item.

    Ordered lists

    An ordered list entry consists of a number and period, or a number period and number, followed by at least one space. There can be spaces or tabs before the first number, but nothing else.
    Ordered lists are auto-numbered, provided the following guidelines are followed:

    1. Two levels, major (2.) and minor (2.4) are supported. Each major entry increments the major number.

    An item can have more than one paragraph, provided each subsequent paragraph starts with one or more spaces or tabs, and there are no intervening blank lines. The leading spaces or tabs will be suppressed in the HTML display.

    2. If the first major entry in a list starts with a number, that number is used as the starting number for the list. Minor levels are always numbered starting at 1.

    2.1 A blank line or regular paragraph that doesn't begin with a space or tab ends the current list and resets numbering.

    2.2 Any continuation paragraph in the same item will have its leading spaces or tabs suppressed.

    Here is a second paragraph for item 2.2.

    And here is a third paragraph, with more leading spaces in the original. Blathering on to make it wrap, blathering on to make it wrap, blathering on to make it wrap.

    3. '#' can be used as a placeholder, but it's not recommended because if you want to refer to a numbered entry you have to know the number. In practice, careful numbering by hand is more useful.

    4. If you use two levels, there should be a major level entry starting off each top-level item, such as the "1." "2." "3." entries in 1., 1.1, 1.2, 2., 2.1, 3., 3.1. Without the major items, the major number will not increment.

    An ordered list example (a bit messed up in the source to show auto-numbering at work):

    3. The first major item, with starting number set to 3.

    3.1 A minor item under 3.

    3.2 Another minor item, incorrectly numbered as 3.3 in the source (corrected to 3.2)

    3.3 Several minor items, carelessly numbered in the source as "#.#" (this will be 3.3)

    3.4 Several minor items, carelessly numbered in the source as "#.#" (this will be 3.4)

    3.5 Several minor items, carelessly numbered in the source as "#.#" (this will be 3.5)

    4. The second major item, correctly numbered in source as 4.

    5. Oops, the source has "6." instead of "5." - this will display as 5.

    5.1 A minor item, 5.1 (source has 6.1)

    5.2 A minor items, 5.2 (source has 6.3)

    5.3 Another minor item. This becomes item 5.3 even though it's "7.1" in the source.

    The source for the above example:

    Emphasis

    Put single asterisks (✱) before and after text to mark it as italic. Put two asterisks (✱✱) both before and after text to mark it as bold. You get <em> for italic and <strong> for bold, which I hope is what you expected.
    For a short code fragment, you can use ✱!✱let x = 10;✱!✱
    This could use a small example. So I'm going to cheat in the original text and use a Unicode heavy asterisk ✱, which Gloss won't convert. The second instance of the example line uses regular asterisks.
    Gloss does ✱italic emphasis✱ and ✱✱bold emphasis✱✱ like this, and code as ✱!✱let x = 10;✱!✱.
    Gloss does italic emphasis and bold emphasis like this, and code as let x = 10;.

    Code blocks

    Code blocks are supported only in .txt files. To see a code block rendered in HTML open the .txt file using IntraMine's Viewer, or convert a .txt file to HTML using gloss2html.pl and open the result in your browser.
    To create a code block in a .txt file:

     • put CODE on a line all by itself

     • follow with your lines of code

     • and finish by putting ENDCODE on a line all by itself.

    Here's an example:
    (there's an invisible space before "CODE" to block rendering)
    ​CODE
    sub InlineJavaScriptForFile {
    my ($fileName) = @_;
    my $result = '';
    my $contents = ReadTextFileWide($JS_DIR . $fileName);
    if (defined($contents) && $contents ne '')
    {
    $result = "<script type=\"text/javascript\">\n$contents\n</script>\n";
    }
    else
    {
    die("Error, could not load JavaScript file |$fileName|\n");
    }
    return($result);
    }
    ​ENDCODE
    which is rendered in the HTML version of this file as
    _STARTCB_FL_
    _STARTCB_sub InlineJavaScriptForFile {
    _STARTCB_ my ($fileName) = @_;
    _STARTCB_ my $result = '';
    _STARTCB_ my $contents = ReadTextFileWide($JS_DIR . $fileName);
    _STARTCB_ if (defined($contents) && $contents ne '')
    _STARTCB_ {
    _STARTCB_ $result = "<script type=\"text/javascript\">\n$contents\n</script>\n";
    _STARTCB_ }
    _STARTCB_ else
    _STARTCB_ {
    _STARTCB_ die("Error, could not load JavaScript file |$fileName|\n");
    _STARTCB_ }
    _STARTCB_
    _STARTCB_ return($result);
    _STARTCB_ }
    _STARTCB_FL_
    Text in CODE/ENDCODE is given some minimal syntax styling using lolight (https://github.com/lrsjng/lolight), and a light background color. Anecdotally this is sufficient to fool anyone in HR into thinking they're looking at code.

    Special characters

    Gloss makes certain words and strings stand out a bit. With slight exceptions for "=>", and "NOTE" they are emphasized wherever they occur. Here's the list:
    and here's how the Viewer displays them:
    🎗TODO
    🎗REMINDER
    🎗REMINDERS
    NOTE (if followed by a non-word character such as a space)
    🐝BUG
    🐝BUGS
    ☛ (that's "=>", either at the start of a line or preceded by space)
    💡IDEA!
    ☑FIXED
    ☑DONE
    💩WTF
    🙂 (type a colon ":" followed by a right parenthesis ")", as you already guessed)
    And as a special bonus, if you put three or more of @ on a line by themselves you will get a "flourish" image that can serve as a section break. Like so:

    Standalone is special

    For most .txt files, links will be put in for any file specifier that matches an indexed file, and glossary entries will be taken from your collection of glossary_master.txt files. However, there are .txt files that need different handling, namely those that you are using as sources for standalone HTML files, as generated by the Glosser service or the gloss2html.pl Perl program. For those, you want to see glossary entries taken from any glossary.txt file in the same folder, and also limit links to files in the same folder, so there's a match with the resulting HTML version of the file. This happens in both the Editor and Viewer if you have a glossary.txt file in the same folder.

    Not wanted on the voyage

    Markdown is aimed at a variety of audiences. Here are some features that documents for intranet use don't really need, for a variety of reasons.
    Gloss doesn't do these
    Item                 Why
    ~~strikethrough~~I have never needed that, have you?
    Definition listGloss provides glossary popups instead. A definition is available wherever a term is used, by stopping the cursor over the term.
    Heading IDGloss links headings automatically: put the heading mentions in double quotes, for example "Overview".
    FootnotesSomething for grander documents.
    Alt text for imagesGloss pops up a view of the image when you put your cursor over the image name. If alt text is needed, you can type it before or after the image name.
    BlockquotePut it in quotes and italicize the author, good enough for most uses.
    Task listTask lists are everywhere. For example, IntraMine's ToDo page🙂
    Gloss does do hashed headings, such as #### This is an h4 heading, but underlining with five or more of = - or ~ just looks better in the original.
    And the last thing not wanted is the line as a unit of comprehension. In a formatted text document there are words and sentences and paragraphs as units of comprehension, but not lines. In Gloss when you press Enter you end a paragraph, not a line, and line wrap keeps all the text visible. Adjust the width of your window to suit your personal line-width taste, and you're done with the concept. Perhaps using a line instead of a paragraph in some other Markdown versions was carried over from source files, where lines are usually important.
    contents.html